🔗 API de Relações e UsuarioRelacoes - Documentação Completa

📋 Visão Geral

A API de Relações e UsuarioRelacoes é responsável por toda a gestão de tipos de relacionamentos e vínculos entre usuários no sistema CordenaAi. Inclui o cadastro de tipos de relação (como Professor, Responsável, Aluno) e a criação de vínculos específicos entre usuários, permitindo estruturar hierarquias e permissões no sistema.

🎯 Endpoints Disponíveis

Módulo Relações (Tipos de Relacionamento)

1. GET /api/Relacoes

Obter Lista de Relações

Descrição: Retorna uma lista completa de todos os tipos de relação cadastrados no sistema
Método: GET
Autenticação: Requerida (JWT Bearer Token)
Parâmetros: Nenhum
Resposta: Array de objetos Relacao
Uso: Utilizado em dropdowns de seleção, configurações de sistema e relatórios

2. POST /api/Relacoes

Criar Nova Relação

Descrição: Cria um novo tipo de relação no sistema
Método: POST
Autenticação: Requerida (JWT Bearer Token)
Body: Objeto Relacao com dados obrigatórios
Resposta: Objeto Relacao criado com ID gerado
Uso: Configuração inicial do sistema, criação de novos tipos de vínculo

3. GET /api/Relacoes/{id}

Obter Relação por ID

Descrição: Retorna os dados completos de um tipo de relação específico
Método: GET
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Resposta: Objeto Relacao completo
Uso: Visualização de detalhes, validação de tipos de relação

4. PUT /api/Relacoes/{id}

Atualizar Relação

Descrição: Atualiza os dados de um tipo de relação existente
Método: PUT
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Body: Objeto Relacao com dados atualizados
Resposta: Objeto Relacao atualizado
Uso: Manutenção de configurações, atualização de descrições

5. DELETE /api/Relacoes/{id}

Excluir Relação

Descrição: Remove um tipo de relação do sistema
Método: DELETE
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Resposta: Confirmação de exclusão
Uso: Limpeza de configurações não utilizadas

Módulo UsuarioRelacoes (Vínculos entre Usuários)

6. GET /api/UsuarioRelacoes/usuario/{identificador}

Obter Relações por Usuário

Descrição: Retorna todas as relações de um usuário específico
Método: GET
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- identificador (path): ID, email, CPF ou username do usuário
Resposta: Array de objetos UsuarioRelacao
Uso: Visualização de vínculos do usuário, relatórios de relacionamentos

7. GET /api/UsuarioRelacoes/responsavel/{identificador}

Obter Relações por Responsável

Descrição: Retorna todas as relações onde o usuário é responsável
Método: GET
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- identificador (path): ID, email, CPF ou username do responsável
Resposta: Array de objetos UsuarioRelacao
Uso: Interface do responsável, gestão de dependentes

8. GET /api/UsuarioRelacoes/{id}

Obter Relação por ID

Descrição: Retorna os dados completos de uma relação específica
Método: GET
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Resposta: Objeto UsuarioRelacao completo
Uso: Visualização de detalhes, edição de vínculos

9. POST /api/UsuarioRelacoes

Criar Relação de Usuário

Descrição: Cria um novo vínculo entre usuários
Método: POST
Autenticação: Requerida (JWT Bearer Token)
Body: Objeto UsuarioRelacao com dados obrigatórios
Resposta: Objeto UsuarioRelacao criado com ID gerado
Uso: Associação de usuários, criação de hierarquias

10. PUT /api/UsuarioRelacoes/{id}

Atualizar Relação de Usuário

Descrição: Atualiza os dados de uma relação existente
Método: PUT
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Body: Objeto UsuarioRelacao com dados atualizados
Resposta: Objeto UsuarioRelacao atualizado
Uso: Modificação de vínculos, alteração de responsabilidades

11. DELETE /api/UsuarioRelacoes/{id}

Excluir Relação de Usuário

Descrição: Remove um vínculo entre usuários
Método: DELETE
Autenticação: Requerida (JWT Bearer Token)
Parâmetros:
- id (path): ID único da relação
Resposta: Confirmação de exclusão
Uso: Remoção de vínculos, limpeza de relacionamentos

🔧 Modelo de Dados

Estrutura da Relação (Tipo de Relacionamento)

{
  "id": "integer",
  "relacaoNome": "string",
  "relacaoDescricao": "string"
}

Estrutura da UsuarioRelacao (Vínculo entre Usuários)

{
  "id": "integer",
  "usuarioId": "string",
  "usuarioNome": "string",
  "usuarioResponsavelId": "string",
  "usuarioResponsavelNome": "string",
  "relacaoId": "integer",
  "relacaoNome": "string",
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

JWT Bearer Token no header Authorization
Permissões específicas baseadas no tipo de usuário:
- Administradores: Acesso completo a todos os endpoints
- Responsáveis: Acesso limitado às suas relações
- Usuários: Acesso apenas às suas próprias relações

📊 Casos de Uso Principais

1. Configuração de Tipos de Relação

POST /api/Relacoes
Content-Type: application/json
Authorization: Bearer {token}

{
  "relacaoNome": "Professor",
  "relacaoDescricao": "Professor da turma"
}

2. Criação de Vínculo entre Usuários

POST /api/UsuarioRelacoes
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "usuarioResponsavelId": "resp-456",
  "relacaoId": 1
}

3. Consulta de Relações por Usuário

GET /api/UsuarioRelacoes/usuario/[email protected]
Authorization: Bearer {token}

4. Consulta de Relações por Responsável

GET /api/UsuarioRelacoes/responsavel/resp-456
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

RelacaoNome: Obrigatório, máximo 100 caracteres
RelacaoDescricao: Opcional, máximo 500 caracteres
UsuarioId: Obrigatório, deve existir no sistema
UsuarioResponsavelId: Obrigatório, deve existir no sistema
RelacaoId: Obrigatório, deve existir no sistema

Regras de Negócio

Identificadores Flexíveis: Suporte a ID, email, CPF ou username
Relacionamentos Únicos: Não permite duplicação de vínculos
Integridade Referencial: Validação de existência de usuários e relações
Auditoria: Todas as operações são logadas
Soft Delete: Relações podem ser inativadas sem exclusão permanente

🚨 Tratamento de Erros

Códigos de Status HTTP

200: Sucesso
201: Criado com sucesso
400: Dados inválidos
401: Não autorizado
403: Acesso negado
404: Relação/Usuário não encontrado
409: Conflito (relação já existe)
500: Erro interno do servidor

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Paginação: Listas retornam máximo 100 registros por página
Rate Limiting: 1000 requests por hora por usuário
Timeout: 30 segundos por requisição

Otimizações

Cache: Dados de relações são cacheados por 5 minutos
Índices: Busca otimizada por identificadores flexíveis
Compressão: Respostas comprimidas com gzip

🔄 Integração com Outros Módulos

Módulos Relacionados

Usuários: Base para criação de vínculos
Atletas: Associação com responsáveis
Equipes: Estruturação hierárquica
Turmas: Organização educacional
Permissões: Controle de acesso baseado em relações

📱 Uso em Aplicações

Web App

Configuração de tipos de relação
Gestão de hierarquias organizacionais
Relatórios de relacionamentos
Interface administrativa

Mobile App

Visualização de vínculos do usuário
Gestão de responsabilidades
Notificações baseadas em relações

🛠️ Manutenção e Monitoramento

Logs Importantes

Criação de novos tipos de relação
Estabelecimento de vínculos entre usuários
Tentativas de acesso não autorizado
Erros de validação de relacionamentos

Métricas Monitoradas

Número de tipos de relação cadastrados
Quantidade de vínculos estabelecidos
Taxa de sucesso das operações
Tempo de resposta dos endpoints

📚 Exemplos Práticos

Fluxo Completo de Configuração

Criação de Tipos de Relação

POST /api/Relacoes
{
  "relacaoNome": "Responsável",
  "relacaoDescricao": "Responsável legal pelo atleta"
}

Estabelecimento de Vínculo

POST /api/UsuarioRelacoes
{
  "usuarioId": "atleta-123",
  "usuarioResponsavelId": "pai-456",
  "relacaoId": 1
}

Consulta de Relacionamentos

GET /api/UsuarioRelacoes/usuario/atleta-123

Fluxo de Gestão Hierárquica

Definição de Estrutura: Criação de tipos de relação
Associação de Usuários: Estabelecimento de vínculos
Consulta de Hierarquia: Visualização de relacionamentos
Manutenção: Atualização e remoção de vínculos

🔍 Identificadores Flexíveis

O sistema suporta identificação de usuários através de:

ID (GUID): Identificador único do sistema
Email: Endereço de email do usuário
Username: Nome de usuário
CPF: Documento de identificação (quando disponível)

Exemplos de Uso

# Por ID
GET /api/UsuarioRelacoes/usuario/123e4567-e89b-12d3-a456-426614174000

# Por Email
GET /api/UsuarioRelacoes/usuario/[email protected]

# Por Username
GET /api/UsuarioRelacoes/usuario/joao.silva

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi